Crate abscissa_core

Abscissa is a microframework for building Rust applications (either CLI tools or network/web services), aiming to provide a large number of features with a minimal number of dependencies, and with a strong focus on security.

Documentation

Features

• command-line option parsing: simple declarative option parser based on clap. The option parser in Abcissa contains numerous improvements which provide better UX and tighter integration with the other parts of the framework (e.g. overriding configuration settings using command-line options).
• components: Abscissa uses a component architecture (similar to an ECS) for extensibility/composability, with a minimalist implementation that still provides such features such as calculating dependency ordering and providing hooks into the application lifecycle. Newly generated apps use two components by default: terminal and logging.
• configuration: Simple parsing of TOML configurations to serde-parsed configuration types which can be dynamically updated at runtime.
• error handling: unified error-handling subsystem with generic error type.
• logging: based on the log to provide application-level logging.
• secrets management: the (optional) secrets module includes a Secret type which derives serde’s Deserialize and can be used to represent secret values parsed from configuration files or elsewhere (e.g. credentials loaded from the environment or network requests)
• terminal interactions: support for colored terminal output (with color support autodetection). Useful for Cargo-like status messages with easy-to-use macros.

Projects Using Abscissa

• Canister: deployment utility for “distroless” containers/microVMs
• cargo-audit: audit Cargo projects for security vulnerabilities
• cosmon: observability tool for Tendermint applications
• ibc-rs: Rust implementation of Interblockchain Communication (IBC) modules and relayer
• rustic: fast, encrypted, and deduplicated backups
• Synchronicity: distributed build system providing BFT proofs-of-reproducibility
• Tendermint KMS: key management system for Tendermint applications
• Zebra: Rust implementation of a Zcash node
• Zerostash: Encrypted and deduplicated backups

Crate Structure

Abscissa presently consists of three crates:

• abscissa: CLI app and application generator - cargo install abscissa
• abscissa_core: main framework library
• abscissa_derive: custom derive support - implementation detail of abscissa_core
• abscissa_tokio: support for launching Tokio runtimes within Abscissa applications

Minimum Supported Rust Version

Requires Rust 1.74 or newer.

Installation

To generate a new Abscissa application, install the abscissa CLI utility:

$ cargo install abscissa

Creating a new Abscissa application

The following commands will generate an Abscissa application skeleton:

$ cargo install abscissa
$ abscissa new my_cool_app

The resulting app is a Cargo project. The following files are particularly noteworthy:

• src/application.rs: Abscissa application type for your app
• src/commands*: application entrypoint and subcommands. Make sure to check out the start.rs example of how to make a subcommand.
• src/config.rs: application configuration
• src/error.rs: error types

Abscissa applications are implemented as Rust libraries, but have a src/bin subdirectory where the binary entrypoint lives. This means you can run the following within your newly generated application:

$ cargo run -- start world

This will invoke the start subcommand of your application (you might want to rename that in your app) which will print the following:

Hello, world!

You can also run the following to print basic help information:

$ cargo run -- --help

Status Macros

// Print a Cargo-like justified status to STDOUT
status_ok!("Loaded", "app loaded successfully");

// Print an error message
status_err!("something bad happened");

// Print an indented attribute to STDOUT
status_attr_ok!("good", "yep");

// Print an error attribute to STDERR
status_attr_err!("error", "yep");

Frequently Asked Questions (FAQ)

Q1: Why is it called “abscissa”?

A1: The word “abscissa” is the key to the Kryptos K2 panel.

Q2: “Abscissa” is a hard name to remember! Got any tips?

A2: Imagine you’re A-B testing a couple of scissors… with attitude.

Testing Framework Changes

The main way to test framework changes is by generating an application with Abscissa’s built-in application generator and running tests against the generated application (also rustfmt, clippy).

To generate a test application and test it automatically, you can simply do:

$ cargo test

However, when debugging test failures against a generated app, it’s helpful to know how to drive the app generation and testing process manually. Below are instructions on how to do so.

If you’ve already run:

$ git clone https://github.com/iqlusioninc/abscissa/

…and are inside the abscissa directory and want to test your changes, you can generate an application by running the following command:

$ cargo run -- new /tmp/example_app --patch-crates-io='abscissa = { path = "$PWD" }'

This will generate a new Abscissa application in /tmp/example_app which references your local copy of Abscissa.

After that, change directory to the newly generated app and run the tests to ensure things are still working (the tests, along with rustfmt and clippy are run as part of the CI process):

$ cd /tmp/example_app # or 'pushd /tmp/example_app' and 'popd' to return
$ cargo test
$ cargo fmt -- --check # generated app is expected to pass rustfmt
$ cargo clippy

Code of Conduct

We abide by the Contributor Covenant and ask that you do as well.

For more information, please see CODE_OF_CONDUCT.md.

License

The abscissa crate is distributed under the terms of the Apache License (Version 2.0).

Copyright © 2018-2024 iqlusion

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Contribution

If you are interested in contributing to this repository, please make sure to read the CONTRIBUTING.md and CODE_OF_CONDUCT.md files first.

Re-exports

• pub extern crate tracing;
• pub use crate::error::framework::FrameworkError;
• pub use crate::error::framework::FrameworkErrorKind;
• pub use crate::application::boot;
• pub use crate::application::Application;
• pub use crate::component::Component;
• pub use crate::config::Config;
• pub use crate::config::Configurable;
• pub use crate::command::Command;
• pub use crate::path::StandardPaths;
• pub use clap;
• pub use fs_err as fs;
• pub use secrecy as secret;

Modules

• application
  Trait for representing an Abscissa application and it’s lifecycle
• command
  Application (sub)command(s), i.e. app entry points
• component
  Application components: extensions/plugins for Abscissa applications.
• config
  Support for managing global configuration, as well as loading it from TOML.
• error
  Error types used by this crate
• map
  An ordered map based on a B-Tree.
• path
  Paths for resources used by the application.
• prelude
  Core prelude: imported in every application’s prelude.rs
• set
  An ordered set based on a B-Tree.
• terminal
  Terminal handling (TTY interactions, colors, etc)
• testing
  Acceptance testing for Abscissa applications.
• thread
  Thread wrapper types.
• trace
  Tracing subsystem

Macros

• ensure
  Ensure a condition holds, returning an error if it doesn’t (ala assert)
• fail
  Create and return an error with a formatted message
• fatal
  Terminate the application with a fatal error, running Abscissa’s shutdown hooks.
• format_err
  Create a new error (of a given kind) with a formatted message
• status_attr_err
  Print a tab-delimited status attribute (in red if colors are enabled)
• status_attr_ok
  Print a tab-delimited status attribute (in green if colors are enabled)
• status_err
  Print an error message (in red if colors are enabled)
• status_info
  Print an informational status message (in cyan if colors are enabled)
• status_ok
  Print a success status message (in green if colors are enabled)
• status_warn
  Print a warning status message (in yellow if colors are enabled)

Structs

• Map
  An ordered map based on a B-Tree.
• SecretBox
  Wrapper type for values that contains secrets, which attempts to limit accidental exposure and ensure secrets are wiped from memory when dropped. (e.g. passwords, cryptographic keys, access tokens or other credentials)
• Version
  SemVer version as defined by https://semver.org.

Enums

• Shutdown
  Types of shutdown recognized by Abscissa

Constants

• VERSION
  Abscissa version

Traits

• Runnable
  Runnable is a common trait for things which can be run without any arguments.
• RunnableMut
  RunnableMut is a Runnable that takes a mutable reference to self.

Type Aliases

• SecretSlice
  Secret slice type.
• SecretString
  Secret string type.

Derive Macros

• Command
• Component
• Runnable